20230322

[shlib.git] / doc / UM.txt.en_US / =2.1.shlibinc and basical usage.txt

doc of shlib

  Copyright (C) 2022- Free Software Foundation, Inc.

  Copying and distribution of this file, with or without modification,
  are permitted in any medium without royalty provided the copyright
  notice and this notice are preserved.

The following contributions warranted legal paper exchanges with the
Free Software Foundation.


# catagory
==========
1.introduction
2.usage of shlib
2.1.include path
2.2.uniq and nest include
2.3.shlib element
2.4.include and laod in sub-proc
2.5.load and unload and reload
2.6.debug info output
2.7.include/load operation for other lib files
3.writing a shlib





# 1.introduction
================
    shlibinc is the basical cmd in shlib. it provide some function and alias
cmd, to implement the feature of library include/load.
    it is different from 'source' cmd in system, the feature listed below:

@ it uses a global dir to store the shlib file, and include/load them without 
  path prefix. a set of function is used for get/set/del include path.
@ it support global dir shlib include, and also support relative path include, 
  it is used as '#include' in c language.
@ include operation can be nested with each other. and the file has been 
  included will not be sourced again, it saves cpu cost. this will help for
  lots of shlib file nested including.
@ load operation is supported. normally, load usefull shlib in system init 
  script, and the include operation in program will be compacted to execute
  the variable init code only. this also saves cpu cost.
@ unload and reload is the relative feature with load cmd. when we debug a 
  shlib, we want to update code in memory, reload is used for this. if some 
  feature is not worked normally in load operation, and unload it, it will
  be included in script every time.
@ this module support debug info output by setting of shlibopt. when option 
  setted, some of the detail info for debug will output to stderr. it is used 
  for debug a new shlib, espacially in shlib nest including.



# 2.usage of shlib
================
        in shell command programe, source is a command to 'include' other script
into current code. but it uses file without global path prefix. and it can not
be un-include in program.
    but 'source' cmd is the base of shlibinc feature.
        look at the code below, and it's a very simple use of shlib.

```
# pay attension to the space between . and shlibinc.
. shlibinc

# this shlib is a general string output shlib with different kinds of output
  info.
include stdio.shlib

dbgout "use the function dbgout() in dbgout.shlib, to output a string.\n"
```

    run this script, and you will get the string outputed by function dbgout, 
which is wroted in stdio.shlib.



# 2.1.include path
==============

    the difference between 'source' and 'include' is that, include has global
library file path.
    the variable SHLIB_PATH is nearly equal to LD_LIBRARY_PATH. and shlibinc 
provide those functions to get/set/del lib path.

@ get_shlib_path, print shlib one path string by one line.
@ get_shlib_path_var <var-name>, get the shlib path in array var.
@ set_shlib_path <PATH>, set whole shlib path string.
@ add_shlib_path <PATH>, append path to shlib path.
@ del_shlib_path <PATH>, delete path by specified string.

    the things to be pay attension for:

@ when same shlib file in different paths(include relative path) is included in 
  script, the sequence of include is the sequence of path string in SHLIB_PATH,
  and use relative path at last.
@ path prefix will be effect to uniq-include. a file in global path, can be include again by a different path prefix.

    generally, we only use the file name for 'include' cmd without "./" or "~/"
prefix or absolute path, even if it can works.



# 2.2.uniq and nest include
=======================

    script execute very slowly. the include operation is a code execution on
cpu, it is different from compile-time language like c/c++. if we include many
shlib, the include operation will cost cpu execution time, and the program will
delay for include shlib.
    many public feature is included by other shlibs. in c/c++, we use #ifdef to
avoid header file re-include. we need the same feature in shlib.

    when we include same shlib in the same process, include and load operation
will skip it by it self. it record shlib file in SHLIB_LIST by load cmd, in
SHLIB_INC_LIST by include cmd.



# 2.3.shlib element
===============

    a library is consisted by those resource:

@ variables, declare create var with -g and -x option. var with -x option can
  be exported in sub-script-proc.
    if the variable declared with -x option, the value can be exported to sub
  process, whatever it is in include or load operation.
@ functions, the default function declare is not exported, it can not be used
  in sub-script-proc.
    functions loaded in shlib can be invoked in sub-proc by 'load' cmd only.
@ alias cmds, the default alias cmds is not exported, it's blank in a new sub
  process.
    alias loaded in shlib can be invoked in sub-proc by 'load' cmd only.

    include or load a shlib, is used to access shlib element to implement some
features. os, include and load operation is orianted to those element.



# 2.4.include and laod in sub-proc
===============================

    another method to save cpu cost is 'load' cmd. 
    it load shlib in system init script, or cmdline. when the shlib included in 
a script program, it will ignore whole source operation. the function has been 
loaded, the alias cmds will be loaded automatically, and it just invoke 
shlib_xxx_init() function to init variables.

    shlib code effective scope:

@ same program, but different process. eg: ( cmd ), cmd will executed in a sub 
  process. but it is forked from current script program, all global variable
  and functions, and alias cmds can be use as the parent program process. but 
  the modification of variables is not modified in parent process.
@ sub-script-process invoking. a normal script cmd invoke in a program, the
  variable in sub-script-proc is kept only with -x option, the function only
  can be invoked by declare -x setting, the alias cmds is blank in 
  sub-script-proc.

    shlibinc provide those alias cmds:

@ PROG_GVAR_INIT <shlib-name>, init global variable in shlib, when the lib file 
  has been loaded.
@ GVAR_INIT <shlib-name>, uniq-include flag setting.
@ uniqlib <shlib-name>, if this lib is included or loaded, it will return from
  source operation, to avoid loading followed shlib code.

    cmd of 'load' is an operation between two process. 

@ when a shlib has been included in the same program, it ignore include shlib,
  and the 'load' cmd is executed as normal.
@ when a shlib has been loaded in the same program, it ignore shlib include 
  and load.
@ when parent program include a shlib, use include and load as normal.
@ when parent program load a shlib, include and load operation will be 
  compacted, it just only invoke shlib_xxx_init() function to init variables 
  in shlib.

    use include and load, it will process those condition automatically.
    the feature of load and uniq-include decrease code execute time for shlib 
using.



# 2.5.load and unload and reload
============================
    if we are writing a shlib, we need to debug it, and testing for load 
operation. if a shlib is loaded, it can not be load again by 'load' cmd.
    use reload to update code for shlib. and use unload to delete it to
decrease memory cost.
    they are used in cmdline as normal.



# 2.6.debug info output
===================
    debug info.

@ file include/load operation info.
@ var/func/alias in loaded file info.


# 2.7.include/load operation for other lib files
============================================
    include operation is a usefull feature to use a file as a lib file. it 
provide global include path, uniq-include, load compactly in sub process.
    if we need another file type to be a library file, we use the defination
function poridev by shlibinc.
        
        imi file is a txt based config file, and i want to use it as a global
paramter storage file. this example shows how to define imi file as a library
file.

```
define_include imi loadimi imiload : "${ROOTFS}/usr/minc"
```

    syntax: define_include <name> <inc-name> <loadcmd> <unloadcmd> <inc-path>

@ <name> : lib file ext name.
@ <inc-name> : include operation name for user.
@ <loadcmd> : the function or cmd invoked by actual file loading.
@ <unloadcmd> : the function or cmd invoked by actual file unloading.
@ <inc-path> : the path of default library path.





# 3.writing a shlib
=================

@ templete.
@ code style & code format.
@ comment.
@ shlib_xxx_init().


















    参考doc/example/templete-code/shlib_templete.shlib。
@ 定义shlib_shlib_init()，用于全局变量的定义和初始化，并在函数定义之后调用。当shlib第一次load时运行。
@ 在include之前调用uniqlib shlib，其下的代码对已load的shlib不运行，避免重复load。
@ 一些代码，像是全局变量初始化，在new-sub-process中需要重新初始化。uniqlib shlib之前调用PROG_GVAR_INIT shlib，调用shlib_shlib_init()之后，return。
@ 文件以comment-section划分为不同的code-section。代码编写时在对应的section中编码。例如public函数和private函数在不同的section存放，这样能较好地看到shlib库的接口函数。
@ public函数的comment信息比较详细，而private函数根据需要编写comment。
@ shlib的include是uniq的，只在首次include时调用shlib_shlib_init()。
@ 
# shlib的include只在当前进程有效，
# shlib在load时，函数可在sub-proc中有效。
# 无论是include还是load，var需要在sub-proc有效，需要使用declare -g -x定义。
# alias在load时，sub-proc不起作用。
# 使用load时，变量在当前proc进行使用，需要在sub-proc的include中重新init。







relative-path in nest inc
lib-path in nest inc
if a file is included, it may be based on relative-path or lib-path. 


@ inlude
# inc path get/set/del.
# inc shlib in lib-path.
# relative-path inc.
# relative-path in nest inc.
# inc priority between pwd  & lib path

@ sub-proc-inc
# nest-uniq-inc shlib in same process.
# include same shlib in sub-proc

@ load
# inc shlib in lib-path.
# relative-path inc.
# relative-path in nest inc.
# inc priority between pwd & lib path

# can't load after include

@ sub-proc-load
# nest-uniq-inc shlib in same process.

# include in same proc, skip include, load deny.
# load in same proc, skip include & load.
# include in parent-proc, include and load as normal.
# load in parent-proc, include and load by shlib_xxx_init() compactly.

@ debug-info
# 

@ unload-reload
# 









#
# @ three things to be payying attension, var, func, alias.
# @ several kinds of load enviroument:
# # 1.include at the first time.
# # 2.include first, and then include.
# # 3.include first, and then load.
# # 4.load at the first time.
# # 5.load first, and then include.
# # 6.load first, and then load.
# # 7.include at the parent process, include in sub-proc.
# # 8.include at the parent process, load in sub-proc.
# # 9.load at the parent process, include in sub-proc.
# # 10.load at the parent process, load in sub-proc.
# @ 
# # for 1 & 4, normal include/load operation. source whole shlib, 
#   but include operation does not set load-flag variable.
# # for 2 & 3 & 5 & 6, the second include/load operation is skipped.
# # for 3, running load again if there is no 'load' executed.
# # in the same process, once include or load, skip next time.
# # for 7 & 8, the first include operation is not effect on sub-proc,
#   it will be include/load as it was not included in parent process.
# # for 9 & 10, if load at the parent process, just invoke xxx_init()
#   to init the global variables, and skip the function loading when
#   it has been loaded.
# 
# @ conclution:
# # in the same process, once include or load, skip next time.
# # include operation is effect only in current process.
# # if load shlib in the parent process, just only invoke xxx_init()
#   to init the global variables in sub-process.
#

#
# @ flags
# # SHLIB_INC_LIST is used to tag include operation.
# # SHLIB_LIST with -x attr is used to tag load operation in different process.
# # uniq include tag have no -x attr, and uniq load set with -x attr. once loaded,
#   just only invoke xxx_init() without whole file loading.
#

# 
# @ content
# # func loaded by load cmd is exported function, but include cmd is not.
# # var declared by include/load cmd is normal var. setting with -x attr 
#   is decided by developer manually.
# # alias can not be loaded in sub-proc. save the alias defination in a var, 
#   re-define them when xxx_init() is invoked.
# 


















@ load命令调用时保存shlib的使用记录。系统定时任务中根据使用频率，以及shlib对内存资源的使用，设置初始化时load一些shlib，减少程序运行时shlib初始化的cpu使用。



[shlibinc]
@ 全局变量名称尽量添加shlib模块的pfx，减少共用name-space的使用。

@ 对程序库文件的操作类型，包括：
# source：最基础的操作，只对脚本库进行函数加载。
# include：对source功能的编程语言化操作。包括lib-path、uniq-inc功能。
# load：对sub-proc的shlib进行source包含，并使shlib在sub-proc中无须重复source。
# reload：shlib的load是uniq的，load之后不进行重复load。但对于shlib更新时，使用reload命令，将已有shlib unload之后，再重新load。

@ include 与 load
# include操作只在当前进程有效，通常用于代码中对shlib的使用。但对已load的shlib进行判断，从而skip库的include。
# load操作在sub-proc中仍可使用，通常用于系统初始化时对shlib的load，减少程序运行时include的cpu使用。


@ shlib的load操作
# 一个shlib功能模块，包含3个部分的定义：var、func、alias。考虑三者在不同进程load时的使用，以及在xxx_init()中的设置。
# first-load对shlib进行source包含，并对var、func、alias的名称或内容进行保存，对func添加-x属性，设置成export的函数。
# 在second-load时，将保存的alias定义，进行重新设置。
# 在second-load时，一些alias在xxx_init()中进行重新设置。
# 在unload时，unset、unalias保存的这些内容。

@ shlib中的var
# var划分为export属性和非export属性，两者区别在于是否在sub-proc中仍可使用。（是否设置export，根据shlib中的func对var的使用）
# 在xxx_init()中，对variable定义和初始化。export属性的变量使用decl_shlib_var定义，包含对变量existing的判断，变量的定义，变量初始化值的设置。

@ shlib中的func
# func在load时始终是export属性的。


@ shlib中的alias
# alias在new-proc时，始终是unexport的。
# alias在first-load时保存定义，在second-load时自动设置。
# 对于一些在定义中包含${}环境变量expanssion的alias，在second-load时调用的xxx_init()中重新定义。


@
# 对于lib在load时的初始化。不同进程load时，以及first load时，xxx_init()函数的运行。一些export属性的变量在初始化时，需考虑变量是否已定义，以及是否需要re-init。
例如：stdio.shlib中的进程id，在first-init时，初始化为当前pid的非export环境变量。在second-init时，变量未定义，重新定义。
例如：term.shlib中定义的一些表示颜色的常量，定义成export属性，init时无须重复初始化，减少cpu消耗。
例如：stdio.shlib中定义的调试信息输出的pfx和sfx，在同一个session下的style相同，所以在second-load时不进行重新设置，根据当前进程的设置使用。定义成export，
例如：

@ 使用cp命令时，不添加-v参数，-v参数使用的absolutly-path包含不同测试环境的路径信息。
@ shlib中的环境变量的定义，需要考虑reload，uniq-include等环境，变量的-g、-x属性，以及变量的名字空间，与local变量定义的问题，-a、-A属性无法export，等。